home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / m2 / m2_part1.lha / modula / dice / dice.LHA / doc / EXTENSIONS.DOC < prev    next >
Text File  |  1991-04-26  |  14KB  |  372 lines
  1.  
  2. extensions/extensions                    extensions/extensions
  3. extensions/EXTENSIONS                    extensions/EXTENSIONS
  4.  
  5.                    COMPILER EXTENSIONS
  6.  
  7.                  AUTO LIBRARY OPENNING
  8.  
  9.     Certain Amiga libraries are supported on an autoinit basis.  Normally
  10.     you declare the library base variable then OpenLibrary() it in your
  11.     main.
  12.  
  13.     If you EXTERN the library base variable instead then it will be brought
  14.     in from auto.lib along with autoinit code to automatically
  15.     OpenLibrary() it on startup and CloseLibrary() it on shutdown.
  16.  
  17.     DICE uses this feature to automatically open floating point libraries,
  18.     dos.library, etc...  The following libraries may currently be openned
  19.     in this fashion (note that if you attempt to use the feature on a
  20.     library that does not support auto-open a link error will occur):
  21.  
  22.     asl.library            (2.0)
  23.     dos.library
  24.     fifo.library
  25.     gadtools.library        (2.0)
  26.     graphics.library
  27.     mathffp.library
  28.     mathtrans.library
  29.     mathieeesingbas.library     (2.0, works w/ 1.3)
  30.     mathieeesingtrans.library   (2.0, works w/ 1.3)
  31.     mathieeedoubbas.library
  32.     mathieeedoubtrans.library
  33.     intuition.library
  34.     layers.library
  35.     utility.library         (2.0)
  36.  
  37.     Others will be added in the future, eventually all the libraries.
  38.  
  39.     Note that the auto-open features is fully upward compatible to earlier
  40.     methods of declaring the base pointer and openning the libraries
  41.     manually.  Declaring a library base variable causes the associated
  42.     autolib routines to NOT be linked into the executable.
  43.  
  44.            TYPE QUALIFIER AND STORAGER QUALIFIER EXTENSIONS
  45.  
  46.     availability:   reg-only = registered users
  47.  
  48.  
  49.     extension    avail        comment
  50.  
  51.     volatile    all        force auto's to NOT be placed in registers
  52.     const    all        place data items in the code section (see -ms/-mS)
  53.     __autoinit    all        cause a subroutine to be run automatically
  54.                 before _main (for variables, puts variable in
  55.                 alternate section)
  56.     __autoexit    all        cause a subroutine to be run automatically
  57.                 before _exit
  58.     __interrupt all        NOT AMIGA COMPATIBLE
  59.     __chip    reg-only    cause storage to be placed in CHIP memory
  60.     __far    all        cause storage to be referenced using absolute-long
  61.     __near    all        cause storage to be referenced using A4-relative
  62.     __aligned    all        cause storage to be aligned on a longword boundry
  63.     __unaligned all        allows structures to be byte-aligned (at your own risk)
  64.     __geta4    reg-only    cause a subroutine to setup the A4 data base
  65.                 pointer
  66.  
  67.     __shared    all        storage is placed in the code section and thus
  68.                 is shared between instances of a resident'd
  69.                 program.  EXPERIMENTAL
  70.  
  71.     __regargs    all        specify function takes registered arguments
  72.                 even if -mr/-mR/-mRR is not used.
  73.  
  74.     __stkargs    all        specify function takes normal stack based
  75.                 args despite the possibility that -mr/-mR/-mRR
  76.                 has been specified.
  77.  
  78.     __dynamic    reg-only    dynamic linking of routines/variables at run-
  79.                 time
  80.  
  81.     volatile
  82.     This storage qualifier normally specifies that the physical storage
  83.     is 'synched' at the end of each line of C code.  DICE already does
  84.     this by virtue of not doing any major optimizations.  Under ANSI
  85.     this storage qualifier also forces auto variables to NOT be placed
  86.     in a register.    This can be important if you use <setjmp.h>
  87.     (see MAN/SETJMP.DOC for more information)
  88.  
  89.     const
  90.     The const type qualifier can be handled in different ways by DICE.
  91.     As of the 2.05.11 version of DC1, any const qualified object is
  92.     placed in the code section.  Before 2.05.11 const qualified
  93.     objects were only placed in the code section if -ms or -mS was
  94.     also given to DCC.
  95.  
  96.     Normally a const qualified item is handled as a near item (pc-rel)
  97.     within the module that declares it, and handled with absolute-long
  98.     references in modules that extern it.
  99.  
  100.     If -ms is used then string constants are made const.  If -mS is
  101.     used then all external references to const items use pc-relative
  102.     instead of the absolute-long addressing mode.  Do NOT use -mS
  103.     unless your final code size is less than 32KBytes.
  104.  
  105.     Using -ms can substantially reduce the number of run-time
  106.     relocations for -r residentable programs as well as the run-time
  107.     dynamically allocated data+bss space.
  108.  
  109.     (refer to DCC.DOC, -ms and -mS options for details)
  110.  
  111.     __autoinit
  112.     __autoexit
  113.  
  114.     These storage qualifiers cause a routine to be called after libraries
  115.     are openned before _main is called (__autoinit), and just before
  116.     libraries are closed after _exit is called (__autoexit).  They may
  117.     be used for low level initialization and shutdown and may not make
  118.     any c.lib calls (i.e. malloc, fopen, open, etc... may not be called)
  119.  
  120.     __autoinit void
  121.     fubar()
  122.     {
  123.         NewList(&MyList);
  124.     }
  125.  
  126.     __autoinit may be used with a variable declaration.  The variable
  127.     is placed in an alternate section.  This is mainly of use for
  128.     ROMable applications to group declared data together, with a base
  129.     section pointer in the ROM startup object and a 'terminator'
  130.     in the last object module.  For example, a 'ROM MODULE LIST' may
  131.     be constructed painlessly using this feature.
  132.  
  133.     __autoinit int a;        /*    altbss,bss    */
  134.     __autoinit int a = 4;        /*    altdata,data    */
  135.     __autoinit const int a;     /*    altcode,code    */
  136.     __autoinit const int a = 4; /*    altcode,code    */
  137.  
  138.     SUGGESTION:  use dcc -a to oberve the assembly generated.  Note
  139.     that BSS data verses INITIALIZED data go into different sections.
  140.  
  141.     __interrupt
  142.  
  143.     This storage qualifier for a subroutine causes all used registers to
  144.     be saved and restored, including the scratch registers, and returns
  145.     via RTE instead of RTS.
  146.  
  147.     THIS KEYWORD IS NOT AMIGA COMPATIBLE
  148.  
  149.     __chip
  150.  
  151.     This storage qualifier forces a static or global data item to be
  152.     placed in CHIP memory.    Normally this precludes being able to make
  153.     such programs resident (-r option), but if you also use the -ms
  154.     option and the 'const' type qualifier you can make such programs
  155.     resident....  The 'const' type qualifier assumes that the contents
  156.     of the object will NEVER be modified!!!
  157.  
  158.     __chip short ImageData[] = { ... };        read-write object
  159.     __chip const short ImageData[] = { ... };   read-only object
  160.  
  161.     __far
  162.  
  163.     __far int a;
  164.  
  165.     This storage qualifier determines how a data object is to be
  166.     referenced.  It overides the data model for the reference and
  167.     forces the ABSOLUTE-LONG addressing mode to be used.
  168.  
  169.     Note that __chip data is automatically forced to be __far.
  170.     When compiling -mD the default is to use __far references.
  171.  
  172.     __near
  173.  
  174.     __near int a;
  175.  
  176.     This storage qualifier forces a small-data model (A4-Relative)
  177.     reference to a data object.  When using the -md (default) data
  178.     model data objects are accessed as near items by default.
  179.  
  180.     __aligned
  181.  
  182.     This storage qualifier forces the static, global, or auto data
  183.     object to be aligned on a longword boundry.
  184.  
  185.     foo()
  186.     {
  187.         __aligned struct FileInfoBlock fib;
  188.         ...
  189.     }
  190.  
  191.     WARNING:    __aligned does not work if this subroutine or any
  192.     higher level subroutine is passed a *structure* where said
  193.     structure is not aligned.  We are talking about passing actual
  194.     structures here, not pointers to structures (which work fine
  195.     with __aligned).
  196.  
  197.     __unaligned
  198.  
  199.     This storage qualifier allows structures to be byte-aligned in
  200.     terms of NOT padding them to the nearest word or longword.
  201.  
  202.         __unaligned struct foo {
  203.         char a;
  204.         } a, b, c;
  205.  
  206.     In the above example, sizeof(a), sizeof(b), and sizeof(c) is 1.
  207.  
  208.     USE AT YOUR OWN RISK.  Accessing word/long/ptr items at odd
  209.     byte addresses is illegal for the 68000 and will generate an
  210.     exception.  This qualifier is useful mainly for character
  211.     structures that must map over a text file.
  212.  
  213.     __geta4
  214.  
  215.     This storage qualifier on a subroutine definition forces the
  216.     subroutine to save A4 and then load A4 with the small-data model
  217.     data pointer on subroutine entry, then restore the original
  218.     contents of A4 on subroutine exit.  This is useful for
  219.     inter-context calls when using the small-data model.
  220.  
  221.     __geta4 void
  222.     fubar()
  223.     {
  224.  
  225.     }
  226.  
  227.     Unfortunately, using this qualifier precludes being able to
  228.     generate a residentable executable since a residentable
  229.     executable's data space pointer is unknown at link time.
  230.  
  231.     __shared
  232.  
  233.     This storage modifier places the global or static variable
  234.     declaration into the code segment, thus this variable will be
  235.     SHARED across multiple running instances of the same program,
  236.     assuming the program has been made RESIDENT.  A program that has
  237.     not been made resident will not share variables.
  238.  
  239.     __config    (UNDER TESTING, DO NOT USE FOR ANY REAL PROJECT)
  240.  
  241.     This storage modifier generates loading and saving code for all
  242.     variables in question.    You should not declare any pointers as
  243.     a saved pointer value will not be valid when the program is run
  244.     later on.
  245.  
  246.     If no configuration file exists the initialized value of the static
  247.     or global storage is used, for example:
  248.  
  249.         __config int a = 34;
  250.  
  251.     'a' will be 34 if no configuration file exists.  If a configuration
  252.     file does exist all __config variables will be overriden with the
  253.     values stored in the configuration file.
  254.  
  255.     The name and version of the configuration file must be specified
  256.     by the programmer as two initialized global variables or a link
  257.     error will occur.  For example:
  258.  
  259.         char *ConfigFile = "s:myprog.config";
  260.         long ConfigVersion = 1;
  261.  
  262.     DICE configuration code will automatically ignore any configuration
  263.     file whos version does not equal ConfigVersion.  As a programmer,
  264.     you must change ConfigVersion if you modify ANY __config
  265.     declaration, the ordering of any __config declaration, or the
  266.     ordering of any object modules in your link.  If you fail to do so,
  267.     the program may attempt to load an invalid configuration.
  268.  
  269.     The configuration is automatically loaded on program startup,
  270.     before _main() (__main from assembly) gets run, and if ConfigFile
  271.     is non-NULL on program exit (_exit) then the configuration will be
  272.     saved.     Thus, __config is supported even if you use the _main()
  273.     entry point and _exit() exit point.
  274.  
  275.     WARNING: ONLY PROCESSES MAY USE THE __CONFIG TYPE QUALIFIER.  If
  276.     you plan to run a program as a task instead of a process then you
  277.     cannot use __config.  Note that any WORKBENCH or CLI run program
  278.     is a process.  DOS handlers are also processes, but it is not
  279.     suggested that __config be used for any program that is to be
  280.     a DOS handler (i.e. a DOS device).  Libraries and exec Devices are
  281.     NOT processes... not even tasks usually, and thus __config may not
  282.     be used for such programs.
  283.  
  284.     __regargs
  285.     __stkargs
  286.  
  287.     Normally these qualifiers are used in conjuction with the -mr,
  288.     -mR, or -mRR flags.  Even so, they are usually used only to
  289.     force a normal C calling convention for callback functions (when
  290.     you supply intuition, graphics, exec, or whomever with a callback
  291.     function the OS will call you with arguments on the stack).
  292.  
  293.     Specifying neither causes the routine to default to either stack
  294.     args or register args depending on the DCC flags.  Specifying
  295.     __stkargs forces the function to use stack based arguments no
  296.     matter what options are used.  Specifying __regargs forces the
  297.     function to use register based arguments in the same manner.
  298.     Specifying both forces the function to generate two entry points
  299.     (same thing occurs by default when -mr is used).
  300.  
  301.     Please refer to the discussion in REGARGS.DOC for more information
  302.  
  303.     __dynamic
  304.  
  305.     The __dynamic storage qualifier is used to declare routines that
  306.     do not exist at link or load time but will be loaded run-time.
  307.     The overall effect is to generate autoinit code to dynamically
  308.     load an indirect pointer to the declared variable/procedure and
  309.     autoexit code to release your references on said pointer.
  310.  
  311.     DICE transparently declares the variables/procedures as pointers
  312.     and transparently indirects whenever they are used in code.  The
  313.     __dynamic feature is INCREDIBLY POWERFUL, allowing a program to
  314.     interface to third-party object modules at run-time.  Generally,
  315.     this type of interface is more desirable than a shared-library
  316.     when the module in question are huge -- do major things, as well
  317.     as allowing third-party replacement of modules without effecting
  318.     program operation or requiring a relinking of the program.
  319.  
  320.     Please refer to DYNAMIC.DOC for a more involved explanation.
  321.  
  322.  
  323.     --------------------------------------------------------------------
  324.  
  325.                DYNAMIC STACKS (-gs option)
  326.  
  327.     DICE now has a new option, -gs, which generates stack checking code for
  328.     every subroutine.  But, unlike SAS/C or MANX, DICE is able to allocate
  329.     new stack chunks when the current stack runs out.  Essentially this
  330.     means that you can compile and run programs which expect a lot of stack
  331.     without having to remember to give a larger STACK command in your
  332.     CLI.  Since DICE allocates and deallocates stack chunks according to
  333.     program usage, an efficient use of the amiga's memory is made.
  334.  
  335.     There are two global variables associated with this option.  You, the
  336.     programmer, may override either or both of them by declaring them
  337.     yourself.  The variables are:
  338.  
  339.     long _stack_fudge = 4096;
  340.     long _stack_chunk = 32768;
  341.  
  342.     The defaults are shown above.  You can modify these variables either
  343.     by declaring them globally or changing them on the fly (usually from
  344.     main()).
  345.  
  346.     _stack_fudge specifies the minimum amount of stack before DICE creates
  347.     a new stack.  This should be AT LEAST 2048 BYTES!  This parameter MUST
  348.     be able to handle the worst case stack usage for any given subroutine.
  349.  
  350.     The second parameter specifies the chunk size for any new stacks
  351.     created.  A new stack is created whenever the current available
  352.     stack goes below _stack_fudge, but only applies to the next level
  353.     of subroutine... the current subroutine (that detected the low stack
  354.     condition) must be able to run in the old stack.  Stacks are freed
  355.     as they become unused.
  356.  
  357.     If for any reason DICE is unable to allocate a new stack, it will
  358.     call the stack_abort() routine.  If you do not define such a routine,
  359.     the one from the library will be used (which abort()s the program).
  360.  
  361.     If you DO define a stack_abort() routine, then you must take one
  362.     of two actions:
  363.  
  364.     (1) abort() or exit() the program
  365.  
  366.     (2) return (causes DICE to retry allocating the stack)
  367.  
  368.     If DICE is unable to reallocate the stack after (2), it will call
  369.     stack_abort() again.
  370.  
  371.  
  372.